Skip to content

Conversation

@arandito
Copy link
Contributor

@arandito arandito commented Oct 30, 2025

Description

This PR replaces the Sphinx-based reStructuredText (RST) documentation generation system introduced in #418 with MkDocs and Markdown for AWS services only. It also updates the docstring format to use the Google style with Markdown descriptions fro all services (AWS and non-AWS).

Key changes:

  • Updates all code generators (Client, Structure, Config, Enum, Union) to output Google style docstrings with Markdown descriptions using MarkdownConverter
  • Adds pandoc CLI tool as a required build dependency to convert Smithy model documentation strings to Markdown for all services
  • Adds AwsMkDocsFileGenerator plugin to generate MkDocs stub files for only AWS services in their docs/ directory
  • Updates README with new pandoc dependency
  • Adds MkDocs configuration file and python dependencies to AWS services
  • Adds codegen utility function to determine if service is AWS or generic.
  • Removes AwsRstDocFileGenerator plugin and RST-to-Markdown conversion logic

Important

This PR only adds standalone docs for individual AWS clients. These can be built in each client and hosted separately. We plan to aggregate these all into a single top-level documentation site in awslabs/aws-sdk-python. This will happen post client generation and will use the stub files generated in docs/ directory for each client. We will also use Material for MkDocs.

Testing

Note

For local testing, please install pandoc v3.8.2 before running code generator.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

@arandito arandito requested a review from a team as a code owner October 30, 2025 19:53
@arandito arandito marked this pull request as draft October 30, 2025 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant